<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Introduction</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Boost.Test">
<link rel="up" href="../index.html" title="Boost.Test">
<link rel="prev" href="../index.html" title="Boost.Test">
<link rel="next" href="intro/design_rationale.html" title="Design rationale">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="intro/design_rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_test.intro"></a><a class="link" href="intro.html" title="Introduction">Introduction</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="intro/design_rationale.html">Design rationale</a></span></dt>
<dt><span class="section"><a href="intro/how_to_read.html">How to read this documentation</a></span></dt>
</dl></div>
<p>
      <span class="epigraph">Test everything that could possibly break</span>
      <span class="epigraph">--XP maxim</span>
    </p>
<p>
      <span class="epigraph">The acceptance test makes the customer satisfied that
      the software provides the business value that makes them willing to pay for
      it. The unit test makes the programmer satisfied that the software does what
      the programmer thinks it does </span> <span class="epigraph">--XP maxim</span>
    </p>
<p>
      What is the first thing you need to do when you start working on new library/class/program?
      That's right - you need to start with the unit test module (hopefully you all
      gave this answer!). Occasionally, you may get away with simple test implemented
      using <code class="computeroutput"><span class="identifier">assert</span></code>s, but any professional
      developer soon finds this approach lacking. It becomes clear that it's too
      time-consuming and tedious for simple, but repetitive unit testing tasks and
      it's too inflexible for most non-trivial ones.
    </p>
<p>
      The Boost.Test library provides both an easy to use and flexible set of interfaces
      for writing test programs, organizing tests into simple test cases and test
      suites, and controlling their runtime execution. Some of Boost.Test's interfaces
      are also useful in production (non-test) environments.
    </p>
<h5>
<a name="boost_test.intro.h0"></a>
      <span class="phrase"><a name="boost_test.intro.starter_example"></a></span><a class="link" href="intro.html#boost_test.intro.starter_example">Starter
      example</a>
    </h5>
<p>
      This is how a minimal single-file test program looks like:
    </p>
<pre class="programlisting"><span class="preprocessor">#define</span> <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> <span class="identifier">My</span> <span class="identifier">Test</span> <a class="co" name="boost_test.intro.c0" href="intro.html#boost_test.intro.c1"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <a class="co" name="boost_test.intro.c2" href="intro.html#boost_test.intro.c3"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>

<a class="link" href="utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">first_test</span><span class="special">)</span> <a class="co" name="boost_test.intro.c4" href="intro.html#boost_test.intro.c5"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
<span class="special">{</span>
  <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
  <a class="link" href="utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> <a class="co" name="boost_test.intro.c6" href="intro.html#boost_test.intro.c7"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a>
  <a class="link" href="utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span> <a class="co" name="boost_test.intro.c8" href="intro.html#boost_test.intro.c9"><img src="../../../../../doc/src/images/callouts/5.png" alt="5" border="0"></a>
<span class="special">}</span>
</pre>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_test.intro.c1"></a><a href="#boost_test.intro.c0"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
          Macro <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> defines the
          name of our program, which will be used in messages.
        </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_test.intro.c3"></a><a href="#boost_test.intro.c2"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
          This includes all the <span class="emphasis"><em>Unit Test Framework</em></span> in a "header-only"
          mode; it even defines function <code class="computeroutput"><span class="identifier">main</span></code>,
          which will call the subsequently defined test cases.
        </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_test.intro.c5"></a><a href="#boost_test.intro.c4"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
<td valign="top" align="left"><p>
          Macro <a class="link" href="utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a> declares
          a <span class="emphasis"><em>test case</em></span> named <code class="computeroutput"><span class="identifier">first_test</span></code>,
          which in turn will run the content of <code class="computeroutput"><span class="identifier">first_test</span></code>
          inside the controlled testing environment.
        </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_test.intro.c7"></a><a href="#boost_test.intro.c6"><img src="../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
<td valign="top" align="left"><p>
          This test checks if <code class="computeroutput"><span class="identifier">i</span></code> is
          non-zero.
        </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_test.intro.c9"></a><a href="#boost_test.intro.c8"><img src="../../../../../doc/src/images/callouts/5.png" alt="5" border="0"></a> </p></td>
<td valign="top" align="left"><p>
          This test checks if <code class="computeroutput"><span class="identifier">i</span></code> has
          value <code class="computeroutput"><span class="number">2</span></code> (something more than
          just evaluating the equality operator).
        </p></td>
</tr>
</table></div>
<p>
      When run, it produces the following output:
    </p>
<pre class="programlisting">Running 1 test case...
test_file.cpp(8): error: in "first_test": check i == 2 has failed [1 != 2]

*** 1 failure is detected in the test module "My Test"
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2022 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="intro/design_rationale.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
